<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] User Guide</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font size="+1">User
Guide</font></b></center>

<p><a name="intro"></a><b>Introduction</b></p>

<p>This user guide describes general concepts of the program and provides an
overview of the other documentation files. retawq has become a quite extensive
program which offers many options and features like different <a
href="wk.html">window kinds</a> and <a href="runmode.html">runmodes</a> which
are unusual for text-mode web browsers. At the beginning, you can ignore most
of the special properties. You can use retawq like most other text-mode
browsers and rarely have to care about anything special if you don't want
to.</p>

<p><a name="tour"></a><b>Guided Tour</b></p>

<p>First, build the executable program as described in <a
href="../INSTALL">INSTALL</a> without caring about all those possible <a
href="ctconfig.html">compile-time configuration options</a>. Start the program
without any <a href="arg.html">command-line options</a>. It presents a web page
which mentions the current version number of the program and possibly
information about some libraries which are used and other things. Technically,
this web page is a document which is contained in one "view" in a window of <a
href="wk.html">window kind</a> "browser window", but we don't yet care.</p>

<p>Surf around a little bit to become familiar with the program; the most
important <a href="key.html">keyboard commands</a> for this are:</p>
<ul>
<li>the cursor up/down and page up/down keys to navigate inside a
document</li>
<li>the Return key to follow the currently highlighted link</li>
<li>the keys "g" and "G" to enter <a href="scheme.html">URLs</a> manually</li>
<li>the cursor left/right keys to go back and forth in the series of
views</li>
</ul>

<p>All these keys let you stay in one single window, which is what you probably
are used to from other text-mode browsers.</p>

<p>When you follow a link with the Return key or visit a URL with the "g"/"G"
keys, a new "view" is created in the current browser window. Such a series of
views seems to be unusual in text-mode browsers, but you probably know a
similar concept from <i>graphical</i> browsers where you have the "Back" and
"Forward" buttons.</p>

<p>Now create some other browser windows by splitting the screen (key "2"), by
opening the current document in a new browser window (key "N") or by simply
creating a new, empty browser window (key "n"). To change between two
simultaneously visible windows when the screen is split, press the tabulator
key. To reach a window which is currently not on screen, use the keys "w", "W"
and "ctrl-w".</p>

<p>Once you are familiar with these basic operations, read some of the other
documentation files: quite a few <a href="scheme.html">URL schemes</a> are
supported, not just HTTP; you might want to provide a <a
href="rtconfig.html">run-time configuration</a>; or maybe you want to use some
<a href="arg.html">command-line options</a>, e.g. to start the program in a
different <a href="runmode.html">runmode</a>; if you often visit the same web
pages, maybe you're interested in the <a href="session.html">sessions</a>
feature; if some of the default keys don't work on your terminal, you can
associate different keys to actions by <a href="keymap.html">configuring the
keymaps</a>; if you want to transfer data over encrypted network connections,
read about <a href="tls.html">TLS/SSL</a> support.</p>

<p>This little tour should have given you a first impression of the "look and
feel" of the program. The further sections explain some general concepts in
detail.</p>

<p><a name="screen"></a><b>Terminal Screen Utilization</b></p>

<p>As mentioned above, you can create an arbitrary number of windows and manage
them with <a href="key.html">keyboard commands</a> like "w", "W" and "ctrl-w"
in curses-like <a href="runmode.html">runmode</a>. At any time, one or two
windows are visible on the screen.</p>

<p>Each visible window has its own <i>title line</i> at its bottom which is
displayed in reverse coloring. The title line always begins with a letter like
"B" or "I" which indicates the <a href="wk.html">window kind</a>. The remainder
of the line contains some kind-specific information like the URL of the
currently displayed document in a browser window.</p>

<p>The bottom line of the screen is used for any of three purposes:</p>
<ul>
<li>to show information about the current window; for example, to show the
progress when you are receiving a web page from an HTTP server in a browser
window</li>
<li>to show a message which informs you about the result of a <a
href="key.html">keyboard command</a>; for example, a text like "saving" when
you started saving a document with the <a href="key.html">keyboard command</a>
"s", or a text like "found" when you searched for a string with the <a
href="key.html">keyboard command</a> "/"</li>
<li>to enter something like a new URL or an HTML form text; cf. the section
"Line Input" in the documentation file <a href="key.html">Keyboard
Handling</a></li>
</ul>
<p>If colors are enabled, error messages appear in red color.</p>

<p>If the <a href="ctconfig.html">compile-time configuration option</a>
OPTION_TG has been set to xcurses, scroll bars are available. (This feature
will be available in other curses variants later too.) They appear at the right
border of the terminal window (if the current document isn't completely
visible) and can be turned on/off with the <a href="rtconfig.html">run-time
configuration option</a> "scroll-bars" and with the <a
href="keymap.html">command action</a> "scroll-bars-flip".</p>

<p><a name="docu"></a><b>Documents</b></p>

<p>The user interface is built around a generic "document" concept. Whenever
the program presents some content or other long text on the screen, this is
done in a document. The most common documents are the layouted HTML web pages
in browser windows.</p>

<p>One advantage of this concept is that you can treat documents mostly in the
same way, no matter where they occur and in which <a href="wk.html">window
kind</a>. For example, you can always use the same <a href="key.html">keyboard
commands</a> to scroll documents or to save them in a file.</p>

<p>If a document is interpreted as a web page, it might contain so-called
"active elements": links and HTML form elements. Active elements are displayed
as underlined text and, unless colors are disabled, in blue color. One of the
currently visible active elements is displayed in reverse coloring; this is the
"current" active element which can be treated with <a href="key.html">keyboard
commands</a> like the "Return" key or "i".</p>

<p><a name="form"></a><b>HTML Forms</b></p>

<p>Some web pages contain HTML forms. In retawq, all (non-hidden) HTML form
fields are presented as "active elements", which are explained in the previous
section. Since text terminals don't offer many layout possibilities, some kinds
of form fields look similiar; to get information about the actual kind of a
field, use the <a href="key.html">keyboard command</a> "i". Some fields have a
distinctive look:</p>

<ul>
<li>"[_]" - an unchecked checkbox</li>
<li>"[X]" - a checked checkbox</li>
<li>"(_)" - an unselected radio button</li>
<li>"(*)" - a selected radio button</li>
</ul>

<p>To change the value of a form field or to "push" a submit/reset button, use
the <a href="key.html">keyboard command</a> "Return". Simple fields like
checkboxes change their value directly this way. For textual input fields, you
are prompted at the bottom of the screen; cf. the section "Line Input" in the
documentation file <a href="key.html">Keyboard Handling</a>. If you want to
change the value of a <i>disabled</i> field for some reason, you might have to
use the <a href="key.html">keyboard command</a> "E" first. The textual values
of <i>password</i> fields are always symbolized by disguising "*"
characters.</p>

<p>When you try to change the value of a <i>selection list</i>, a menu pops up;
to change the value, select an option from the menu.  The currently selected
option is always marked with a "+" character in the menu. Disabled options are
marked with a "-" character; this mark is only a "warning": retawq allows you
to select disabled options, but the web page author presumably thought that
nobody should actually do it. Most selection lists only allow a single selected
option at any time; if you select an option in such a list, the previously
selected option is automatically un-selected. In special multi-option lists, on
the other hand, you have to choose a selected option explicitly to un-select
it; only the "first" ("topmost") selected option from the menu is shown in the
web page.</p>

<p>You can't yet upload local files with HTML forms. (Technobabble: the form
field control type "file select" isn't yet handled on form submission. The
default values for such fields aren't (and won't be) taken from the HTML source
code because this could lead to the accidental upload of local files when users
aren't aware that a form contained such fields - that could cause bad security
and privacy problems.)</p>

<p><a name="userdir"></a><b>User Directory</b></p>

<p>The path to the retawq user directory is something like
"/home/<i>your_home</i>/.retawq/" by default, depending on the environment
variable "HOME"; you can choose a different path explicitly with the <a
href="arg.html">command-line option</a> "--userdir".</p>

<p>This directory can contain several important files and sub-directories as
described below; the most important file is probably the <a
href="rtconfig.html">run-time configuration</a> file "config". You can manually
edit, move or remove anything in this directory as you like, but please do this
only when retawq isn't running - otherwise problems might occur.</p>

<p>A note which is related to security and privacy: this directory might
contain information which only you should be able to read, e.g. if you received
a document via encrypted <a href="tls.html">TLS</a> connections and it's stored
in the (not yet implemented) disk cache; the directory, especially the <a
href="rtconfig.html">run-time configuration</a> file, might contain
security-relevant settings which only you should be able to modify, e.g. the
paths of local CGI scripts which may be executed. For such reasons, you should
make sure that only you can access the contents of this directory; for example,
you should execute a shell command like "chmod go-rwx
/home/<i>your_home</i>/.retawq/".</p>

<p>In future versions, this directory will contain many more things, e.g. a
disk cache; if you want to put your own files or directories into it, their
names should not begin with a lowercase letter, to avoid later conflicts.</p>

<ul>
<li>config - the <a href="rtconfig.html">run-time configuration</a> file</li>
<li>session - the standard <a href="session.html">session</a> file; this is
used when you apply the <a href="arg.html">command-line option</a>
"--resume-session" without an explicit argument</li>
</ul>

<p><a name="cache"></a><b>Caching</b></p>

<p>retawq caches some of the information which it gets while it runs.
Currently, everything is only cached in RAM, none of the information is stored
in files; this means that all such information is "forgotten" when you quit the
program. The following might be cached:</p>

<ul>
<li>documents - as long as you keep a reference to a document, e.g. in a
window, the document is kept in a cache; to refresh a document in a browser
window, you can use the <a href="key.html">keyboard commands</a> "r" and "R" to
reload the document</li>
<li>URL history - the most recently visited URLs; to inspect this cache or
visit one of the URLs, use the <a href="key.html">keyboard command</a>
"u"</li>
<li>DNS lookup results - the association of hostnames with IP addresses (DNS:
Domain Name System); you can inspect this cache by visiting the <a
href="scheme.html">URL</a> "about:hostinfo"; you can't yet modify/refresh this
cache manually</li>
<li>HTTP state mechanism ("cookies") - cookies are only cached as explicitly
allowed by the <a href="rtconfig.html">run-time configuration options</a>
"http-cookies" and "https-cookies"; you can inspect this cache by visiting the
<a href="scheme.html">URL</a> "about:hostinfo", where the cached cookies appear
near their respective hosts; this cache is automatically refreshed when a
server sends new cookies</li>
</ul>

<p><a name="env"></a><b>Environment Variables</b></p>

<p>Depending on the actual configuration and activities, retawq might use the
following environment variables:</p>

<ul>
<li>COLUMNS - the number of columns of the terminal; relevant if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_TG has been
set to bicurses (built-in curses) or xcurses mode</li>
<li>DISPLAY - this is used to detect whether retawq is run in a terminal
emulator in a graphical environment; relevant if the <a
href="rtconfig.html">run-time configuration option</a> "termwintitle" says
so</li>
<li>HOME - your home directory, e.g. "/home/<i>your_home</i>/"; for example,
this is used as the base of the default user directory, cf. the respective
section above</li>
<li>LANG - the locale for internationalization of user interface texts;
relevant if the <a href="ctconfig.html">compile-time configuration option</a>
OPTION_I18N has been enabled</li>
<li>LINES - the number of lines of the terminal; relevant if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_TG has been
set to bicurses (built-in curses) or xcurses mode</li>
<li>STY - this is used to detect whether retawq is run inside GNU <a
href="http://www.gnu.org/software/screen/">screen</a>; relevant if the <a
href="rtconfig.html">run-time configuration option</a> "termwintitle" says
so</li>
<li>TERM - the terminal type; relevant if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_TG has been
set to bicurses (built-in curses) mode and "probably" in most other curses
variants too</li>
<li>TERMINFO - the path of a non-default directory which contains the terminfo
files; relevant if the <a href="ctconfig.html">compile-time configuration
option</a> OPTION_TG has been set to bicurses (built-in curses) mode</li>
</ul>

<p>Additionally, retawq might <i>set</i> environment variables for "local-cgi"
<a href="scheme.html">URLs</a> as defined in the CGI specification.</p>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
